---
title: CLI
description: Use the CLI to manage and enhance your HeroUI project components.
---

# CLI

The CLI offers a comprehensive suite of commands to initialize, manage, and improve your HeroUI projects. It enables you to `add`, `remove`, or `upgrade` individual components, assess the health of your project, and more.

## Installation

Requirements:

- [Node.js version 18.17.x or later](https://nodejs.org/en/)

<CarbonAd/>

<Steps>

### Global Installation

To install the `CLI` globally, execute one of the following commands in your terminal:

<PackageManagers
  commands={{
    npm: "npm install heroui-cli -g",
    yarn: "yarn add heroui-cli -g",
    pnpm: "pnpm add heroui-cli -g",
    bun: "bun add heroui-cli -g",
  }}
/>

### Without Installation

Alternatively, you can use the `CLI` without a global installation by running the following command:

<PackageManagers
  commands={{
    npm: "npx heroui-cli@latest",
    yarn: "yarn dlx heroui-cli@latest",
    pnpm: "pnpm dlx heroui-cli@latest",
    bun: "bunx heroui-cli@latest",
  }}
/>

</Steps>

## Quick Start

Once the `CLI` is installed, run the following command to display available commands:

```codeBlock bash
heroui
```

This will produce the following help output:

```codeBlock bash
HeroUI CLI <version>

A command line tool for seamless integration with HeroUI

Usage: heroui [command]

Options:
  -v, --version  Show the version number
  --no-cache     Disable cache, by default data will be cached for 30m after the first request
  -h, --help     Display help for commands

Commands:
  init [options] [projectName]       Start a new HeroUI project
  add [options] [components...]      Add HeroUI components to your project
  upgrade [options] [components...]  Update HeroUI components to the latest versions
  remove [options] [components...]   Remove HeroUI components from your project
  list [options]                     Show details of installed components
  env [options]                      Display debug information about the local environment
  doctor [options]                   Diagnose problems in your project
  help [command]                     Get help on a specific command
```

## init

Initialize a new HeroUI project using the `init` command. This sets up your project with the necessary configurations.

```codeBlock bash
heroui init my-heroui-app
```

<Spacer y={4} />

You will be prompted to configure your project:

```codeBlock bash
┌  Create a new project
│
◇  Select a template (Enter to select)
│  ● App (A Next.js 14 with app directory template pre-configured with HeroUI (v2) and Tailwind CSS.)
│  ○ Pages (A Next.js 14 with pages directory template pre-configured with HeroUI (v2) and Tailwind CSS.)
│  ○ Vite (A Vite template pre-configured with HeroUI (v2) and Tailwind CSS.)
│
◇  New project name (Enter to skip with default name)
│  my-heroui-app
│
◇  Select a package manager (Enter to select)
│  ● npm
│  ○ yarn
│  ○ pnpm
│  ○ bun
│
◇  Template created successfully!
│
◇  Next steps ───────╮
│                    │
│  cd my-heroui-app  │
│  npm install       │
│                    │
├────────────────────╯
│
└  🚀 Get started with npm run dev
```

Install the dependencies to start the local server:

<PackageManagers
  commands={{
    npm: "cd my-heroui-app && npm install",
    yarn: "cd my-heroui-app && yarn install",
    pnpm: "cd my-heroui-app && pnpm install",
    bun: "cd my-heroui-app && bun install",
  }}
/>

Start the local server:

<PackageManagers
  commands={{
    npm: "npm run dev",
    yarn: "yarn run dev",
    pnpm: "pnpm run dev",
    bun: "bun run dev",
  }}
/>

## add

Add components to your HeroUI project with the add command. This command manages component dependencies and updates your project configurations.

Without specifying a specific component:

```codeBlock bash
heroui add
```

<Spacer y={4} />

You will be prompted to select the components you wish to add:

```codeBlock bash
? Which components would you like to add? › - Space to select. Return to submit
Instructions:
    ↑/↓: Highlight option
    ←/→/[space]: Toggle selection
    [a,b,c]/delete: Filter choices
    enter/return: Complete answer

Filtered results for: Enter something to filter

◯  accordion
◯  autocomplete
◯  avatar
◯  badge
◯  breadcrumbs
◉  button
◯  card
◯  checkbox
◯  chip
◯  code
```

To add a specific component:

```codeBlock bash
heroui add button
```

You will see an output confirming the addition of the component:

```codeBlock bash
Adding the required dependencies: @heroui/button

Tailwind CSS settings have been updated in: /project-path/tailwind.config.js

✅ Components added successfully
```

## upgrade

Upgrade all the HeroUI components within your project.

```codeBlock bash
heroui upgrade --all
```

Upgrade specific HeroUI components within your project using the upgrade command to ensure they are up to date.

```codeBlock bash
heroui upgrade button
```

You will be asked to confirm the upgrade:

```codeBlock bash

╭───────────────────────── Component ─────────────────────────╮
│  @heroui/button              ^2.0.11  ->  ^2.0.31       │
╰─────────────────────────────────────────────────────────────╯

Required min version: @heroui/theme>=2.1.0, tailwindcss>=3.4.0
╭───────────────────── PeerDependencies ─────────────────────╮
│  @heroui/theme               2.0.1    ->  2.1.0        │
│  tailwindcss                     ^3.2.3   ->  ^3.4.0       │
╰────────────────────────────────────────────────────────────╯
2 minor, 1 patch

? Would you like to proceed with the upgrade? › - Use arrow-keys. Return to submit.
❯   Yes
    No
```

Upon confirmation, the command will execute and provide an output similar to:

```codeBlock bash
✅ Upgrade complete. All components are up to date.
```

## remove

Remove components from your HeroUI project with the remove command. This helps in managing the project's
component structure and dependencies.

```codeBlock bash
heroui remove button
```

A confirmation prompt will be displayed:

```codeBlock bash
❗️ Components slated for removal:
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│   Package              │   Version              │   Status   │   Docs                                        │
│──────────────────────────────────────────────────────────────────────────────────────────────────────────────│
│   @heroui/button   │   2.0.27 🚀latest      │   stable   │   https://heroui.com/docs/components/button   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

? Confirm removal of these components: › - Use arrow-keys. Return to submit.
❯   Yes
    No
```

Following confirmation, the output will indicate successful removal:

```codeBlock bash
✅ Successfully removed the specified HeroUI components: @heroui/button
```

## list

List all installed HeroUI components in your project with the list command. This provides a clear overview of what is currently included in your project.

```codeBlock bash
heroui list
```

The output will detail each component:

```codeBlock bash
Current installed components:

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│   Package                    │   Version              │   Status    │   Docs                                              │
│───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────│
│   @heroui/autocomplete   │   2.0.10 🚀latest      │   newPost   │   https://heroui.com/docs/components/autocomplete   │
│   @heroui/badge          │   2.0.24 🚀latest      │   stable    │   https://heroui.com/docs/components/badge          │
│   @heroui/button         │   2.0.27 🚀latest      │   stable    │   https://heroui.com/docs/components/button         │
│   @heroui/chip           │   2.0.25 🚀latest      │   stable    │   https://heroui.com/docs/components/chip           │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

## doctor

Diagnose and resolve issues within your project using the doctor command. This ensures your project's health and proper configuration.

```codeBlock bash
heroui doctor
```

Depending on your project's status, you might see:

```codeBlock bash
✅ Your project has no detected issues.
```

Or, if issues are detected:

```codeBlock bash
❌ Your project has 1 issue that requires attention
```

## env

Display detailed information about your project's environment settings using the env command. This includes system, dependencies, and configuration details.

```codeBlock bash
heroui env
```

The output will reflect your current environment setup:

```codeBlock bash
Current installed components:

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│   Package                    │   Version              │   Status    │   Docs                                              │
│───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────│
│   @heroui/autocomplete   │   2.0.10 🚀latest      │   newPost   │   https://heroui.com/docs/components/autocomplete   │
│   @heroui/badge          │   2.0.24 🚀latest      │   stable    │   https://heroui.com/docs/components/badge          │
│   @heroui/button         │   2.0.27 🚀latest      │   stable    │   https://heroui.com/docs/components/button         │
│   @heroui/chip           │   2.0.25 🚀latest      │   stable    │   https://heroui.com/docs/components/chip           │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Environment Info:
  System:
    OS: darwin
    CPU: arm64
  Binaries:
    Node: v18.18.2
```

## API Reference

Explore the complete CLI commands and features in the [API References](/docs/api-references/cli-api).

For updates and source code, visit the [GitHub Repository](https://github.com/heroui-inc/heroui-cli).
